[Chapter 33] 33.3 The K Configuration Command
Author: Bryan Costales & Eric Allman
Date: 1999-01-06T20:22:30Z

#

| Chapter 33 Database Macros |

## 33.3 The K Configuration Command

The `K` configuration command is used to associate a symbolic name with a database file. The symbolic name will later be used in the RHS of rules. The form of the `K` command looks like this:

>     Kname class args

The `name` is the symbolic name. The `class` is the kind of database to use (see Section 33.3.2, "The class"). The `args` specifies the location and properties of the database file (see Section 33.3.3, "The args"). We describe each in turn.

### 33.3.1 The name

The `name` portion of the `K` configuration command immediately follows the `K`. Whitespace between the `K` and the `name` is optional.

>     K name class args

>      optional whitespace

The name must begin with a letter or digit and may contain only letters, digits, and the underscore character. For example:

>     K local_hosts       good
>     K $andCents         bad

If you begin a `name` with a bad character, the following error will be printed and that `K` line will be ignored:

>     configfile: line num: readcf: config K line: no map name

If a bad character appears in the middle of a name, the part preceding the bad character will be taken as the `name`, and the part following the bad character will be taken as the `class`. For example, the `name` `me@home` will produce this error:

>     configfile: line num: readcf: map me: class home not available

The case of the letters in `name` does not matter. All names are converted to lowercase before they are stored.

### 33.3.2 The class

Recall that the `class` portion of the `K` configuration command follows the `name`:

>     Kname class args

Note that whitespace between the `name` and the `class` may be a joined indented line, which allows commenting and improves readability:

>     Kname        # Why this name
>             class     # Why this class
>             args      # and so on

The `class` is the database type. It must be one of the classes listed in Table 33.3.

Table 33.3: Possible K Command Classes
Class |  | Version | Description
--- | --- | --- | ---
btree | Section 33.8.1 | V8.1 and above | Berkeley's db form of database
bestmx | Section 33.8.2, bestmx | V8.7 and above | Look up the best MX record for a host
dbm | Section 33.8.3 | V8.1 and above | Really ndbm supplied with most versions of UNIX
dequote | Section 33.8.4, dequote | V8.1 and above | A pseudo map for removing quotation marks
hash | Section 33.8.5, hash | V8.1 and above | Berkeley's db form of database
hesiod | Section 33.8.6 | V8.7 and above | MIT network user authentication services
host | Section 33.4.3, "$[ and $]: A Special Case" | V8.1 and above | Internal table to store and look up hostnames
implicit | Section 33.8.8, implicit | V8.1 and above | Search for an aliases database file
ldapx | Section 33.8.9 | V8.8 and above | The Lightweight Directory Access Protocol
netinfo | Section 33.8.10 | V8.7 and above | NeXT Computers network information services
nis | Section 33.8.11 | V8.1 and above | Sun's Network Information Services (NIS)
nisplus | Section 33.8.12 | V8.7 and above | Sun's newer Network Information Services (NIS+)
null | Section 33.8.13, null | V8.7 and above | Provide a never found service
program | Section 33.8.14, program | V8.7 and above | Run an external program to look up the key
sequence | Section 33.8.15, sequence | V8.7 and above | Search a series of maps
stab | Section 33.8.16, stab | V8.1 and above | Internally load aliases into the symbol table
switch | Section 33.8.17, switch | V8.7 and above | Internal hook to auto-build sequences
text | Section 33.8.18, text | V8.7 and above | Look up in flat text files
userdb | Section 33.8.19, userdb | V8.7 and above | Look up in the User Database
user | Section 33.8.20, user | V8.7 and above | Look up local passwd information

All of these classes are described in Section 33.8, "Alphabetized Reference" at the end of this chapter. If the `class` is not one of those listed, or if support for the `class` was not compiled in, the following error is printed and the `K` command is ignored:

>     configfile: line num: readcf: map mehome: class badclass not available

The case of the `class` is ignored by sendmail. That is, `hash`, `Hash`, and `HASH` are all the same.

### 33.3.3 The args

The `args` of the `K` configuration command follow symbolic name and class type:

>     Kname class args

The `args` specify (among other things) the location of the database file or the name of a network map. The `args` is like a miniature command line, and its general form looks like this:

>     switches file_or_map

The `switches` are letters prefixed with a `-` character that modify the use of the database. (We'll discuss them in the next section.) The `file_or_map` is the location of the database file or the name of a network map. The `file_or_map` should exclude the .pag and .dir suffixes for dbm class files and exclude the .db suffix for hash or btree class files.

A database or map is opened for reading when the configuration file is processed. If the `file` cannot be opened (and the `-o` is omitted; see Section 33.3.4.8, "-o the database file is optional (V8.1 and above)"), an appropriate error is printed. The `file_or_map` should be an absolute pathname of a file (such as /etc/uuhosts) or a literal network map name (such as hosts.byname). An `nis` map specification can include a domain:

>     map@domain

Relative filenames (names that omit a leading `/`) are interpreted as relative to the current directory of the process that invoked sendmail and should never be used.

### 33.3.4 The switches

The `switches` must follow the `class` and precede the `file_or_map`:

>     Kname class switches file_or_map

If any `switches` follow `file_or_map`, they are silently ignored. [3] All `switches` begin with a `-` character and are listed in Table 33.4.

> [3] This is true as of version 8.8.4. Future versions may change the semantics of the `K` line such that switches may follow.

Table 33.4: K Command Switches
Switch |  | Version | Description
--- | --- | --- | ---
`-A` | Section 33.3.4.1, "-A append values for duplicate keys (V8.7 and above)" | V8.7 and above | Append values for duplicate keys
`-a` | Section 33.3.4.2, "-a append tag on successful match (V8.1 and above)" | V8.1 and above | Append tag on successful match
`-f` | Section 33.3.4.3, "-f don't fold keys to lowercase (V8.1 and above)" | V8.1 and above | Don't fold keys to lowercase
`-k` | Section 33.3.4.4, "-k specify column for key (V8.7 and above)" | V8.7 and above | Specify column for key
`-m` | Section 33.3.4.5, "-m suppress replacement on match (V8.1 and above)" | V8.1 and above | Suppress replacement on match
`-N` | Section 33.3.4.6 | V8.1 and above | Append a null byte to all keys
`-O` | Section 33.3.4.7, "-O adaptive versus never add a null (V8.2 and above)" | V8.2 and above | Adaptive versus never add a null
`-o` | Section 33.3.4.8 | V8.1 and above | The database file is optional
`-q` | Section 33.3.4.9, "-q don't strip quotes from key (V8.7 and above)" | V8.7 and above | Don't strip quotes from key
`-s` | Section 33.3.4.10, "-s space replacement character (V8.7 and above)" | V8.7 and above | Space replacement character
`-v` | Section 33.3.4.11, "-v specify the value's column (V8.7 and above)" | V8.7 and above | Specify the value's column
`-z` | Section 33.3.4.12, "-z specify the column delimiter (V8.7 and above)" | V8.7 and above | Specify the column delimiter

If a switch other than those listed is specified, that switch is silently ignored.

Not all switches work with all classes. Some classes use many switches; others use none. The switches that are used by each class are shown in Table 33.5.

Table 33.5: Which Class Uses Which Switches
Class | Switches
--- | ---
btree | `-A -a -f -m -N -O -o -q`
bestmx | `-a -q`
dbm | `-A -a -f -m -N -O -o -q`
dequote | `-a -s`
hash | `-A -a -f -m -N -O -o -q`
hesiod | `-a -m -o -q`
host | `-a -m -q`
implicit | `-q`
ldapx | `-a -f -m -N -O -o -q`
netinfo | `-a -k -m -q -v`
nisplus | `-a -f -k -m -o -q -v -z`
nis | `-a -f -m -o -q`
null |
program | `-a -m -o -q`
sequence |
stab | `-q`
switch | `-q`
text | `-a -f -k -m -o -q -v -z`
userdb | `-a -f -m -q`
user | `-a -m -q -v`

Some classes of databases use special switches that are not available to the broad class of databases. Others redefine the meaning of some switches. These special switches are shown in Table 33.6. Future versions of sendmail may be changed in such a way that it may be possible to have only one list.

Table 33.6: Specialty Class Switches
Switch | Class or Vendor | Description
--- | --- | ---
`-b` | ldapx | Base from which to begin the search
`-d` | Sun | Use domain wide information (see Section 38.16, "K Command's -d switch")
`-h` | ldapx | Host that serves this network database
`-l` | ldapx | Time limit to timeout connection
`-n` | ldapx | Retrieve attribute names only, not values
`-p` | ldapx | Port to use when connecting to host
`-R` | ldapx | Don't auto chase referrals
`-s` | ldapx | Search scope of "base," "one," or "sub"

#### 33.3.4.1 -A append values for duplicate keys (V8.7 and above)

Ordinarily, when sendmail builds (rebuilds) an aliases database, it objects to duplicate keys on the left of the colon:

>     staff:  bill
>     staff:  leopold         this is an error

But sometimes, in automating for example, such duplicates are necessary. In such instances, the `-A` switch can be used with the `AliasFile` (`A`) option (see Section 34.8.1, AliasFile (A)) to cause duplicates to be silently appended:

>     staff:  bill
>     staff:  leopold
>     ... silently modified by sendmail to internally become
>     staff:  bill, leopold

Note that this process is further illustrated in Section 24.4.4, "Duplicate Entries and Automation".

The `-A` database switch is useful only with alias files, because those are the only files that sendmail rebuilds on its own.

#### 33.3.4.2 -a append tag on successful match (V8.1 and above)

When a key is looked up in a database (from inside the `$(` and `$)` operators of the RHS of rules), a successfully found key is replaced by its data. If the `-a` switch is given, the text following that switch, up to the first delimiting whitespace character, is appended to the replacement data. For example:

>     -a              appends  nothing
>     -a.             appends  .
>     -a,MAGICTOKEN   appends  ,MAGICTOKEN

The text to be appended is taken literally. Quotation marks and backslashed characters are included without interpretation, so whitespace cannot be included in that text. Because the rewritten RHS is normalized as an address, special address expressions (such as parentheses) should be avoided. The use of appended text is one of two methods used for recognizing a successful lookup in rules. We'll discuss the other, `$:`, in Section 33.4.1, "Specify a Default with $:".

#### 33.3.4.3 -f don't fold keys to lowercase (V8.1 and above)

Ordinarily, sendmail will normalize a key to lowercase before looking it up in the database. If the keys in the database are case-sensitive ("TEX" is considered different from "tex," for example), the `-f` switch should be used to prevent this normalization. Note that if the `-f` switch is omitted (the default), the database must have been created with all lowercase keys (also the default).

#### 33.3.4.4 -k specify column for key (V8.7 and above)

Beginning with V8.7, sendmail began to support a flat text-file form of database. The /etc/hosts file is an example of such a flat file, in that it is organized in a line-by-line manner:

>     123.45.67.89      here.our.domain

When such files are read as databases (with the `text` class; see Section 33.8.18), you need to specify which column is the key and which is the value.

For `nisplus` and `netinfo` maps, the `-k` switch specifies the name (text) of the desired column.

When the `-k` switch specifies which column is the key, its absence defaults to 0 for the `text` class and to the name of the zeroth column for the `nisplus` class. Note that the numbered columns are indexed beginning with 0 for the first and 1 for the second. See also `-v` (see Section 33.3.4.11) for the value's column (`text` and `nisplus` only) and `-z` (see Section 33.3.4.12) for the column delimiter (`text` only).

#### 33.3.4.5 -m suppress replacement on match (V8.1 and above)

Ordinarily, a successful lookup in a database or map causes the key to be replaced by its value. When the intention is to merely verify that the key exists (not replace it), the `-m` switch can be used to suppress replacement. For example, the values that are returned from the hosts.byname NIS map are not generally useful (they contain multiple hostnames). In looking up a key in this map (with `$(` and `$)`; see Section 33.4), the `-m` switch prevents those multiple names from wrongly replacing the single hostname in the key. Note that the `-a` (see Section 33.3.4.2) can still be used to append a suffix to a successful lookup. Also, the `$:``default` (see Section 33.4.1) is still used if the lookup fails.

#### 33.3.4.6 -N append a null byte to all keys (V8.1 and above)

If a database was created with makemap's `-N` switch (see Section 33.2.1.3) to include the terminating zero byte with each key, this `K` configuration command `-N` switch may be specified to force all lookups to also include a zero byte. Note that `-N` is not needed for the `nis` class and, if included, is ignored. See also `-O` below.

#### 33.3.4.7 -O adaptive versus never add a null (V8.2 and above)

If neither `-N` nor `-O` is specified, sendmail uses an adaptive algorithm to decide whether or not to look for the terminating zero byte. The algorithm starts by accepting either. If the first key looked up is found to end with a terminating zero byte, the algorithm will thereafter look only for keys with terminating zero bytes. If the first key that is looked up is found to not end with a terminating zero byte, the algorithm will thereafter look only for keys without terminating zero bytes.

If this `-O` switch is specified, sendmail never tries a zero byte, which can speed matches. Note that if both `-N` and `-O` are specified, sendmail will never try to match at all, thus causing all lookups to appear to fail.

#### 33.3.4.8 -o the database file is optional (V8.1 and above)

Ordinarily, sendmail will complain if a database file cannot be opened for reading. If the presence of a database file is optional (as it may be on certain machines), the `-o` switch should be used to tell sendmail that the database is optional. Note that if a database is optional and cannot be opened, all lookups will silently fail for rules that use that database.

#### 33.3.4.9 -q don't strip quotes from key (V8.7 and above)

Ordinarily, sendmail strips all the nonescaped quotation marks (those not prefixed with a backslash) from a key before looking it up. For example, the following key:

>     "Bob \"bigboy\" Roberts \(esq\)"@bob.com

will have its nonescaped quotation marks removed to end up like this:

>     Bob "bigboy" Roberts (esq)@bob.com

Note that all escaped characters are de-escaped (have the backslash removed) during this process.

When quotation marks and escaped characters need to be preserved in a key before it is looked up, you can use the `-q` switch with the `K` configuration command. The `-q` switch suppresses dequoting and de-escaping.

#### 33.3.4.10 -s space replacement character (V8.7 and above)

The `dequote` class (see Section 33.8.4) refuses to remove quotation marks if doing so will result in an illegal address. For example, internal space characters are illegal in addresses:

>     "a b"           becomes       "a b"

The `-s` switch causes all the quoted space characters to be changed into a character that you specify just before the dequoting process.

>     Kdequote dequote -s+

Here, we specify that quoted strings will have quoted spaces converted into a plus before dequoting. Therefore, the above conversion becomes the following:

>     "a b"           becomes       a+b

The `-s` switch is only of use with the `dequote` class. Note that the `lpadx` class uses the `-s` switch differently (see Table 33.6 in Section 33.3.4, "The switches").

#### 33.3.4.11 -v specify the value's column (V8.7 and above)

The manner in which the key and its value are visually displayed in flat, sequential, text files and certain network services, may not be directly suitable for use in maps. A `text` class file, for example /etc/hosts, may display the key on the right and the value on the left:

>     123.45.67.89      here.our.domain

For such circumstances the `-v` switch can be used with the `K` command to specify the column or item that will be returned as the value when a key is matched. For example:

>     Kaddr text -k1 -v0 /etc/hosts

For `nisplus` and `netinfo` maps, the `-v` switch specifies the name (text) of the value's column.

This `-v` switch specifies which column is the value to return. If it is omitted, it defaults to 0 for the `text` class and to the last named column for the `nisplus` class. Note that text columns are indexed beginning with 0 for the first and 1 for the second. See also `-k` (see Section 33.3.4.4) for the key's column and `-z` (see Section 33.3.4.12) for the column delimiter.

#### 33.3.4.12 -z specify the column delimiter (V8.7 and above)

Flat, sequential text files have columns of information delimited from each other with a variety of characters:

>     123.45.67.89      here.our.domain           /etc/hosts uses a whitespace
>     nobody:*:65534:65534::/:                    /etc/passwd uses a colon

The `-z` switch can be used to specify a delimiter whenever the default delimiter of whitespace is not appropriate. In the case of the /etc/passwd file, a database declaration might look like this:

>     Kuid text -z: -k2 -v0 /etc/passwd  # map to convert uid to login name

The default is whitespace for the `text` class. It is a comma for the `netinfo` class.

33.2 Create Files with makemap |  | 33.4 Use Maps with $( and $) in Rules